//+------------------------------------------------------------------+
//|                   ArrayUInt.mqh 无符号32位整数数组类头文件       |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include "Array.h"  // 引入基础数组类头文件，CArrayUInt 继承自 CArray
//+------------------------------------------------------------------+
//| CArrayUInt 类                                                    |
//| 功能：用于管理 uint 类型（无符号32位整数）的动态数组类            |
//| 核心特性：取值范围大（0~4294967295）、无符号（仅非负）、4字节内存占用 |
//| 继承关系：派生自基础数组类 CArray，支持无符号32位整数的动态增删、排序、查找等操作 |
//+------------------------------------------------------------------+
class CArrayUInt : public CArray
  {
protected:
   uint              m_data[];           // 存储无符号32位整数的核心数组容器（每个元素占4字节）

public:
   /**
    * @brief 构造函数：初始化 CArrayUInt 类实例
    * @details 初始化数组容量（m_data_max）、已存储元素数量（m_data_total）等成员变量，为无符号32位整数存储做准备
    */
                     CArrayUInt(void);

   /**
    * @brief 析构函数：销毁 CArrayUInt 类实例
    * @details 调用 Shutdown 方法释放数组占用的内存，避免内存泄漏（4字节元素内存管理高效）
    */
                    ~CArrayUInt(void);

   //--- 对象类型识别方法
   /**
    * @brief 获取当前数组对象的类型标识
    * @return int - 类型标识，固定返回 TYPE_UINT（表示无符号32位整数类型数组）
    */
   virtual int       Type(void) const { return(TYPE_UINT); }

   //--- 文件操作相关方法（按 INT_VALUE 格式读写，适配32位整数）
   /**
    * @brief 将数组中的无符号32位整数数据写入指定文件（按4字节无符号整数格式存储）
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 创建，权限包含写入，支持文本/二进制模式）
    * @return bool - 操作结果：true 表示所有元素均写入成功，false 表示任一元素写入失败（如文件句柄无效）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从指定文件读取无符号32位整数数据到数组（按4字节无符号整数格式读取）
    * @details 读取时自动适配无符号特性，确保数值在 0~4294967295 范围内，避免符号位错误
    * @param file_handle [in] 已打开的文件句柄（需提前通过 FileOpen 创建，权限包含读取，支持文本/二进制模式）
    * @return bool - 操作结果：true 表示所有元素均读取成功，false 表示读取失败（如文件格式错误、长度不足）
    */
   virtual bool      Load(const int file_handle);

   //--- 动态内存管理方法
   /**
    * @brief 为数组预留指定大小的空闲内存空间
    * @details 检查当前剩余空闲空间，不足时按预设步长扩容（4字节元素扩容成本适中，平衡性能与内存占用）
    * @param size [in] 需要预留的空闲元素（无符号32位整数）数量
    * @return bool - 操作结果：true 表示预留成功，false 表示 size≤0 或内存分配失败
    */
   bool              Reserve(const int size);

   /**
    * @brief 调整数组总容量（超出容量的元素会被截断删除）
    * @param size [in] 调整后的数组总容量（包含已存储元素和空闲空间，总内存占用=size×4字节）
    * @return bool - 操作结果：true 表示容量调整成功，false 表示 size<0 或内存分配失败
    */
   bool              Resize(const int size);

   /**
    * @brief 彻底清空数组并释放所有占用的内存
    * @details 重置数组数据、总容量、已存储元素数量等成员变量，将内存归还给系统
    * @return bool - 操作结果：true 表示清理成功，false 表示数组内存释放失败
    */
   bool              Shutdown(void);

   //--- 数组填充相关方法（需注意无符号特性和取值范围）
   /**
    * @brief 向数组末尾添加一个无符号32位整数元素
    * @param element [in] 要添加的 uint 类型元素（取值范围：0~4294967295，超出范围会自动截断为32位无符号值）
    * @return bool - 操作结果：true 表示添加成功，false 表示内存不足
    */
   bool              Add(const uint element);

   /**
    * @brief 将外部 uint 数组的所有元素添加到当前数组末尾
    * @param src [in] 外部 uint 类型数组（需传入数组引用，确保数组有效，元素自动适配无符号范围）
    * @return bool - 操作结果：true 表示所有元素添加成功，false 表示内存不足
    */
   bool              AddArray(const uint &src[]);

   /**
    * @brief 将另一个 CArrayUInt 实例的所有元素添加到当前数组末尾
    * @param src [in] 指向另一个 CArrayUInt 实例的指针（需先通过 CheckPointer 验证有效性）
    * @return bool - 操作结果：true 表示添加成功，false 表示指针无效或内存不足
    */
   bool              AddArray(const CArrayUInt *src);

   /**
    * @brief 在数组指定索引位置插入一个无符号32位整数元素
    * @details 插入位置及后续元素自动后移（4字节元素移动效率稳定），数组长度加1
    * @param element [in] 要插入的 uint 类型元素（需在 0~4294967295 范围内，避免截断导致数据异常）
    * @param pos [in] 插入位置的索引（从0开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示位置无效或内存不足
    */
   bool              Insert(const uint element,const int pos);

   /**
    * @brief 将外部 uint 数组的所有元素插入到当前数组指定位置
    * @param src [in] 外部 uint 类型数组（需传入数组引用）
    * @param pos [in] 插入位置的索引（从0开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示位置无效或内存不足
    */
   bool              InsertArray(const uint &src[],const int pos);

   /**
    * @brief 将另一个 CArrayUInt 实例的所有元素插入到当前数组指定位置
    * @param src [in] 指向另一个 CArrayUInt 实例的指针（需验证指针有效性）
    * @param pos [in] 插入位置的索引（从0开始，需满足 0≤pos≤当前数组长度）
    * @return bool - 操作结果：true 表示插入成功，false 表示指针无效、位置无效或内存不足
    */
   bool              InsertArray(const CArrayUInt *src,const int pos);

   /**
    * @brief 用外部 uint 数组的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组所有元素，再将外部数组的无符号32位整数完整复制（4字节复制效率高）
    * @param src [in] 外部 uint 类型数组（需传入数组引用）
    * @return bool - 操作结果：true 表示赋值成功，false 表示内存不足
    */
   bool              AssignArray(const uint &src[]);

   /**
    * @brief 用另一个 CArrayUInt 实例的内容覆盖当前数组（赋值操作）
    * @details 先清空当前数组所有元素，再复制源实例的元素和排序状态（保持无符号特性一致性）
    * @param src [in] 指向另一个 CArrayUInt 实例的指针（需验证指针有效性）
    * @return bool - 操作结果：true 表示赋值成功，false 表示指针无效或内存不足
    */
   bool              AssignArray(const CArrayUInt *src);

   //--- 数组元素访问方法（无效索引返回INT_MAX，需注意与有效元素区分）
   /**
    * @brief 获取数组指定索引位置的无符号32位整数元素
    * @param index [in] 要访问的元素索引（从0开始，需满足 0≤index<当前数组长度）
    * @return uint - 对应索引的元素（0~4294967295）；若索引无效，返回 INT_MAX（2147483647，需注意其为有效 uint 值）
    */
   uint              At(const int index) const;

   /**
    * @brief 重载 [] 运算符，通过索引直接访问数组元素（等价于 At 方法）
    * @param index [in] 要访问的元素索引（从0开始，需满足 0≤index<当前数组长度）
    * @return uint - 对应索引的元素（0~4294967295）；若索引无效，返回 INT_MAX（2147483647）
    */
   uint              operator[](const int index) const { return(At(index)); }

   //--- 最小值/最大值查找方法（适配无符号32位范围）
   /**
    * @brief 在数组指定范围内查找最小无符号32位整数的索引
    * @param start [in] 查找范围的起始索引（从0开始）
    * @param count [in] 查找的元素个数（需满足 start + count ≤ 当前数组长度）
    * @return int - 最小元素所在的索引；若范围无效，返回 -1
    */
   int               Minimum(const int start,const int count) const { return(CArray::Minimum(m_data,start,count)); }

   /**
    * @brief 在数组指定范围内查找最大无符号32位整数的索引
    * @param start [in] 查找范围的起始索引（从0开始）
    * @param count [in] 查找的元素个数（需满足 start + count ≤ 当前数组长度）
    * @return int - 最大元素所在的索引；若范围无效，返回 -1
    */
   int               Maximum(const int start,const int count) const { return(CArray::Maximum(m_data,start,count)); }

   //--- 数组元素修改方法
   /**
    * @brief 更新数组指定索引位置的无符号32位整数元素
    * @param index [in] 要更新的元素索引（需满足 0≤index<当前数组长度）
    * @param element [in] 新的 uint 类型元素（取值范围：0~4294967295，超出范围会自动截断）
    * @return bool - 操作结果：true 表示更新成功，false 表示索引无效
    */
   bool              Update(const int index,const uint element);

   /**
    * @brief 将数组指定索引的元素按指定偏移量移动位置
    * @param index [in] 要移动的元素原始索引（需在有效范围内）
    * @param shift [in] 偏移量（正数表示向后移动，负数表示向前移动，需确保移动后位置有效）
    * @return bool - 操作结果：true 表示移动成功，false 表示位置越界或偏移量为0
    */
   bool              Shift(const int index,const int shift);

   //--- 数组元素删除方法
   /**
    * @brief 删除数组指定索引位置的元素
    * @details 删除后，后续元素自动前移（4字节元素移动效率稳定），数组长度减1
    * @param index [in] 要删除的元素索引（需满足 0≤index<当前数组长度）
    * @return bool - 操作结果：true 表示删除成功，false 表示索引无效
    */
   bool              Delete(const int index);

   /**
    * @brief 删除数组中指定范围的元素（闭区间 [from, to]）
    * @details 删除后，后续元素自动前移，数组长度减少（to - from + 1）
    * @param from [in] 删除范围的起始索引（需≥0）
    * @param to [in] 删除范围的结束索引（需≥from 且 < 当前数组长度）
    * @return bool - 操作结果：true 表示删除成功，false 表示范围无效
    */
   bool              DeleteRange(int from,int to);

   //--- 数组比较方法（按无符号32位值严格匹配）
   /**
    * @brief 比较当前数组与外部 uint 数组是否完全相等
    * @details 需满足：1. 元素个数相同；2. 对应位置的 uint 值严格相等（无符号32位值无精度误差，直接 == 判定）
    * @param array [in] 要比较的外部 uint 类型数组（需传入数组引用）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等（长度/元素值不同）
    */
   bool              CompareArray(const uint &array[]) const;

   /**
    * @brief 比较当前数组与另一个 CArrayUInt 实例是否完全相等
    * @details 需满足：1. 元素个数相同；2. 对应位置的 uint 值严格相等（无符号特性一致）
    * @param array [in] 指向要比较的 CArrayUInt 实例的指针（需验证指针有效性）
    * @return bool - 比较结果：true 表示完全相等，false 表示不相等（指针无效/长度/元素值不同）
    */
   bool              CompareArray(const CArrayUInt *array) const;

   //--- 有序数组操作方法（按无符号32位值大小排序）
   /**
    * @brief 向有序数组中插入元素（保持数组升序/降序特性，按0~4294967295数值大小排序）
    * @param element [in] 要插入的 uint 类型元素（0~4294967295）
    * @return bool - 操作结果：true 表示插入成功且数组保持有序，false 表示数组未排序或内存不足
    */
   bool              InsertSort(const uint element);

   /**
    * @brief 在有序数组中查找指定无符号32位元素的索引
    * @param element [in] 要查找的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回对应索引，未找到/数组未排序返回 -1
    */
   int               Search(const uint element) const;

   /**
    * @brief 在有序数组中查找第一个“大于”指定无符号32位元素的索引（按数值大小）
    * @param element [in] 参考的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回对应索引，未找到（如所有元素≤目标）/数组未排序返回 -1
    */
   int               SearchGreat(const uint element) const;

   /**
    * @brief 在有序数组中查找第一个“小于”指定无符号32位元素的索引（按数值大小）
    * @param element [in] 参考的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回对应索引，未找到（如所有元素≥目标）/数组未排序返回 -1
    */
   int               SearchLess(const uint element) const;

   /**
    * @brief 在有序数组中查找第一个“大于或等于”指定无符号32位元素的索引
    * @param element [in] 参考的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回对应索引，未找到/数组未排序返回 -1
    */
   int               SearchGreatOrEqual(const uint element) const;

   /**
    * @brief 在有序数组中查找第一个“小于或等于”指定无符号32位元素的索引
    * @param element [in] 参考的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回对应索引，未找到/数组未排序返回 -1
    */
   int               SearchLessOrEqual(const uint element) const;

   /**
    * @brief 在有序数组中查找指定无符号32位元素第一次出现的索引
    * @param element [in] 要查找的 uint 类型元素（数组中可能存在多个相同值）
    * @return int - 查找结果：找到时返回第一次出现的索引，未找到/数组未排序返回 -1
    */
   int               SearchFirst(const uint element) const;

   /**
    * @brief 在有序数组中查找指定无符号32位元素最后一次出现的索引
    * @param element [in] 要查找的 uint 类型元素（数组中可能存在多个相同值）
    * @return int - 查找结果：找到时返回最后一次出现的索引，未找到/数组未排序返回 -1
    */
   int               SearchLast(const uint element) const;

   /**
    * @brief 对数组进行线性查找（遍历数组，适用于无序数组，按数值严格匹配）
    * @param element [in] 要查找的 uint 类型元素（0~4294967295）
    * @return int - 查找结果：找到时返回第一个匹配元素的索引，未找到返回 -1
    */
   int               SearchLinear(const uint element) const;

protected:
   /**
    * @brief 快速排序算法：对数组指定范围元素按无符号32位数值排序（内部使用，不对外暴露）
    * @param beg [in] 排序范围的起始索引（需≥0）
    * @param end [in] 排序范围的结束索引（需≥beg 且 < 当前数组容量）
    * @param mode [in] 排序模式（默认0，通常表示升序，具体逻辑继承自父类 CArray）
    */
   virtual void      QuickSort(int beg,int end,const int mode=0);

   /**
    * @brief 快速查找算法：在有序数组中定位无符号32位元素位置（内部使用，为 Search 系列提供支持）
    * @details 基于二分法实现，按0~4294967295数值大小比较，返回精确匹配或近似位置的索引
    * @param element [in] 要查找的 uint 类型元素（0~4294967295）
    * @return int - 查找的位置索引（若找到则为匹配元素索引，未找到则为最后比较的中间位置）
    */
   int               QuickSearch(const uint element) const;

   /**
    * @brief 数组内部内存移动：将指定范围的无符号32位元素从源位置复制到目标位置（内部使用）
    * @details 用于插入、删除等操作时的元素位置调整，4字节元素复制效率稳定，无内存碎片风险
    * @param dest [in] 目标位置的起始索引（需≥0）
    * @param src [in] 源位置的起始索引（需≥0）
    * @param count [in] 要移动的元素个数（需满足 src + count ≤ 当前数组长度）
    * @return int - 操作结果：成功返回目标位置起始索引，失败返回 -1
    */
   int               MemMove(const int dest,const int src,int count);
  };
//+------------------------------------------------------------------+